Meeting Pearls 1/Meeting Pearls Vol 1 (1994).iso/installed_progs/text/faqs/sgi.faq.performer

Internet Message Format | 1994-05-07 | 47.1 KB

Subject: SGI performer Frequently Asked Questions (FAQ)
Newsgroups: comp.sys.sgi.misc,comp.answers,news.answers
From: [e-mail] (The SGI FAQ group)
Date: 6 May 1994 06:00:50 GMT

Archive-name: sgi/faq/performer
Last-modified: Sun May  1 10:47:21 CDT 1994

    SGI performer Frequently Asked Questions (FAQ)

This is one of the Silicon Graphics FAQ series, which consists of:

    SGI admin FAQ - IRIX system administration
    SGI apps FAQ - Applications & compilers
    SGI graphics FAQ - Graphics and user environment customization
    SGI hardware FAQ - Hardware
    SGI inventor FAQ - IRIS Inventor
    SGI misc FAQ - Introduction & miscellaneous information
    SGI performer FAQ - IRIS Performer
    SGI pointer FAQ - Pointer to the other FAQs

Read the misc FAQ for information about the FAQs themselves.  Each FAQ
is posted to comp.sys.sgi.misc and to the news.answers and comp.answers
newsgroups (whose purpose is to store FAQs) twice per month.  If you
can't find one of the FAQs with your news program, you can get it by
anonymous FTP from one of these sites:

    rtfm.mit.edu:/pub/usenet/comp.sys.sgi.misc/
    rtfm.mit.edu:/pub/usenet/news.answers/sgi/faq/
    rtfm.mit.edu:/pub/usenet/comp.answers/sgi/faq/
    viz.tamu.edu:/pub/sgi/faq/

Note that rtfm.mit.edu is home to many other FAQs and informational
documents, and is a good place to look if you can't find an answer
here. If you can't use FTP, send mail to [e-mail] with
the command 'send usenet/news.answers/ftp-list/faq' on a line by itself
in the text, and it will send you a document describing how to FTP by
mail. You can also read a hypertext version of the FAQs at

    http://www.cis.ohio-state.edu/hypertext/faq/usenet/sgi/top.html

The SGI FAQs are freely distributable and we encourage wide circulation.
The contents are accurate as far as we know, but the usual disclaimers
apply. Please send additions and changes to [e-mail].

Topics covered in this FAQ:
---------------------------
   -1- What is IRIS Performer?
   -2- Where can I get more technical information about IRIS Performer?
   -3- Where can I get more product information about IRIS Performer?
   -4- How does IRIS Performer relate to IRIS Inventor?
   -5- What are the released versions of IRIS Performer?
   -6- Is there a IRIS Performer file format?
   -7- What database file formats can IRIS Performer read?
   -8- Is there an IRIS Inventor file reader for IRIS Performer?
   -9- What are the .tlf files used by the Performer Town and Village?
  -10- What are the minimum requirements for using IRIS Performer?
  -11- Binary Compatibility on different machines
  -12- Binary Compatibility on different releases
  -13- Guaranteeing Real Time performance
  -14- How do I make GL calls from within a IRIS Performer program?
  -15- How do I overlay graphics on top of my Performer scene?
  -16- What is the difference between phases FREE, FLOAT, and LOCK?
  -17- Which rendering primitives does IRIS Performer support?
  -18- How do I do triangle meshes in Performer?
  -19- What is pfInit(): mmap failed for /dev/zero ?
  -20- =============== KNOWN PROBLEMS ===============
  -21- Performer Town or Village demos
  -22- Antialiasing
  -23- Z buffer configuration on 4.0.5 RealityEngine
  -24- Coplanar Polygons & pfDecal on certain platforms
  -25- Networked graphics
  -26- Transparency
  -27- Frame control on low- and mid-range machines
  -28- Timing on pre-1992 platforms
  -29- 1.2 Bug Billboard normals and intersections
  -30- 1.2 Bug Billboards with multiple pfGeoSets
  -31- 1.2 Bug Flattening transformation hierarchies
  -32- 1.2 Bug Gangdraw and cursor loading
  -33- 1.2 libpf Bug Hang on Exit, 5.2 VGX
  -34- 1.2 libpf Cull with overlapped draw latency
  -35- 1.2 libpf Cull with overlapped draw hang
  -36- 1.2 libpf Transparency Sorting
  -37- 1.2 libpf Multiple EarthSky fog
  -38- 1.2 libpf Bug Limit Phase
  -39- 1.2 libpr Highlighting when using wireframe
  -40- 1.2 libpf APPCULLDRAW does not honor LIMIT/FLOAT/LOCK phases
  -41- 1.2 libpf Phase toggling overlapped cull and draw
  -42- 1.2 libpf pfDataPool warning on exit
  -43- 1.2 libpf Multi-channel stats warning messages
  -44- 1.2 libpf Video warnings on Indy when multiprocessed
  -45- 1.2 stats Frame statistics for lightpoints
  -46- 1.2 stats Pixel fill statistics under 4.0.5 on RealityEngine
  -47- 1.2 libpr Directional pfLightPoints
  -48- 1.2 libpfutil pfuCollide is jerky
  -49- 1.2 libpfutil pfuSaveImage broken
  -50- 1.2 libpfsgi pfLoadDxf loader is incomplete
  -51- 1.2 libpfsgi pfLoadIv loader is incomplete
  -52- 1.2 GLX Overlay text with GLX on 4.0.5
  -53- 1.2 GLX Toggling antialiasing with GLX on 4.0.5 RealityEngine
  -54- 1.2 GLX Toggling antialiasing with GLX on any RealityEngine
  -55- 1.2 GLX on 4.0.5 Indigo, sample programs hang on startup.
  -56- 1.2 samples smallfly drive models broken
  -57- 1.2 samples pickfly drops core under abuse
  -58- 1.2 samples detail example broken on 4.0.5
  -59- 1.2 friends Belvis makefile requires pmake
  -60- 1.2 friends Toon has bad models and textures
  -61- 1.2 docs pfuGetGLXWin wrong on reference page
  -62- 1.2 docs pfuLockDownApp gives the incorrect location
  -63- 1.1 Bug with FP underflow
  -64- 1.1 Bug with Multipipe Onyx
  -65- 1.1 Bug Installing on Indy or Indigo2 XL
  -66- 1.1 Bug Unable to determine Indy graphics type
  -67- 1.1 Bug perfly cannot find libpf.so on Indy running 5.1
  -68- 1.1 Bug perfly FP error messages in 5.0.1
  -69- 1.1 Bug Installation on IRIX 5.2 - missing prerequisites
  -70- 1.0/1.1 Bug intersections with pfSwitch'es
  -71- 1.0/1.1 Bug with pfTexture()
  -72- 1.0/1.1 Bug with pfAntiAlias()
  -73- 1.0/1.1 Bug with pfFlatten()
  -74- 1.0/1.1 Bug with pfSequences
  -75- 1.0/1.1 Bug with pfClosestPtOnPlane()
  -76- 1.0/1.1 Bug on ELAN/XS with wireframe PFGS_QUADS
  -77- 1.0 Doc Bug in pfMakePolarSeg() man page
  -78- 1.0 Doc Bug in pfDispList() man page
  -79- 1.0 Doc Bug in PFPG (simple.c)
  -80- 1.0 Bug in pfGetTime()
  -81- 1.0 Bug in pfNodeBBox()
  -82- 1.0 Bug in pfInitGfx() with Z-buffer on RealityEngine
  -83- 1.0 Bug in libpfflt combineLODs()
  -84- 1.0 Bug with two-sided material and pfMtlColorMode()
  -85- 1.0 Bug in pfFilePath()
  -86- 1.0 Bug in pfGetCurGState()
  -87- 1.0 Bug in pfGetCurState()
  -88- 1.0 Bug with cloned scenes
  -89- 1.0 Bug intersections in collide.c
  -90- 1.0 Bug with flattened pfLightPoints
  -91- 1.0 Bug intersections with pfSequences
  -92- 1.0 Bug intersections with non-indexed quads

----------------------------------------------------------------------

Subject:    -1- What is IRIS Performer?
Date: 13 Apr 94 00:00:01 EST

IRIS Performer is a software development environment that supports
programmers implementing high performance graphics applications on
Silicon Graphics products.  It offers both high level facilities for
visual simulation and virtual reality tasks and an application-neutral
high-performance hardware-oriented graphics toolkit.

The outer application specific layer of IRIS Performer implements the
tasks needed by visual simulation applications: it performs culling
so that only potentially visable geometry is sent to the graphics
hardware; it controls multiple display channels; it provides fast
intersection tests with simulation databases; and most importantly,
it orchestrates all of this in parallel with rendering on multiple
processor IRIS systems.

The lower-level rendering portion of IRIS Performer is designed for
maximum performance: its efficient data structures reflect the
details of CPU, cache, and memory system architectures; its tuned
rendering loops convert the system CPU into an optimized data
movement engine; and its optimized state management system optimizes
hardware utilization.

IRIS Performer provides a high-performance portability path across
the Silicon Graphics product line. The low level library is
implemented as a hardware-specific shared library, so applications
based on IRIS Performer can achieve peak performance on graphics
systems from Indy to RealityEngine2 without changes or
recompilation.

The product includes a programmer's guide and printed man pages, as
well as on-line man pages, test and demonstration programs, and
complete real-time visual simulation applications. These applications
are provided in source form as an examples of how to build real-time
simulation systems using IRIS Performer.

And lastly, the distribution includes a wide variety of source code,
demos, models, and utilities that have been provided by 3rd party
vendors for your use.  We call these vendors "friends of Performer"
and we encourage you to sample their wares.

------------------------------

Subject:    -2- Where can I get more technical information about IRIS
                Performer?
Date: 06 Oct 93 00:00:01 EST

The best method is to join the IRIS Performer mailing list.

The list is intended to be an unmoderated, free-form discussion of
IRIS Performer with issues both technical and non-technical; and to
provide feedback to Silicon Graphics about the product.  Much like
the comp.sys.sgi.* newsgroups, it is not an official support channel
but is monitored by several interested SGI employees familiar with
the toolkit.

To become a subscriber to the IRIS Performer mailing list you must
send email to:

    [e-mail]

New subscribers are added "by hand".  Once your request is processed
you will recieve submission/posting instructions, some guidelines,
and a current copy of the Performer Frequently-Asked-Questions (FAQ)
list.

------------------------------

Subject:    -3- Where can I get more product information about IRIS
                Performer?
Date: 06 Jun 93 00:00:01 EST

For product information about IRIS Performer or SGI Visual Simulation
issues contact John Burwell ([e-mail]).  To learn about
SGI Virtual Reality solutions contact Joshua Mogal [phone]
([e-mail]).  To just give in and buy a copy call SGI Direct
at 1-800-800-7441 (product SC4-PERF-1.2), or to have both a
demonstration and a presentation call your local SGI sales office.

------------------------------

Subject:    -4- How does IRIS Performer relate to IRIS Inventor?
Date: 26 Jun 93 00:00:01 EST

The short answer is, Performer was designed for vis-sim, while
Inventor was designed to be more general purpose.

IRIS Performer is for developers who need to extract maximum
performance from SGI machines for visual simulation, virtual reality,
game development, and high-end CAD systems.  Often these applications
need multi-processor Onyx systems with multiple RealityEngine
pipelines with a high degree of parallelism and running at fixed
frame rates.

Inventor is designed for maximum programmer productivity when writing
other kinds of 3D applications, like modelling, animation,
visualization, etc.

Both toolkits are general purpose enough that they could be extended
into the domain of the other, but the question you should consider is
"what is the *fundamental* goal of my graphics development?" If it's
portability to non-SGI systems, easy X-window system integration, or
handy graphic widgets, IRIS Inventor is for you.  If it's brochure-
level performance in advanced graphic applications for the specific
domains listed above, then IRIS Performer would be the likely tool.

------------------------------

Subject:    -5- What are the released versions of IRIS Performer?
Date: 8 Apr 94 00:00:01 EST

IRIS Performer 1.2/IRIX5:  For machines running IRIX 5.2 or above
IRIS Performer 1.2/IRIX4:  For machines running IRIX 4.0.5(A-J) only
IRIS Performer 1.1:  (now obsolete) For machines running IRIX 5.x only
IRIS Performer 1.0:  (now obsolete) For machines running IRIX 4.x only

Note that 1.2 is shipped for both 4.0.5 and 5.2 systems.  You should
only install that version of IRIS Performer that is appropriate for
your machine.  The IRIS Performer version is indicated by the "Irix4"
or "Irix5" string in each product name.  Irix4 products should only
be installed on 4.0.5 systems and Irix5 products should only be
installed on 5.2 systems.

When a choice is possible between IRIX 5.2 and IRIX 4.0.5, IRIX 5.2
is preferable.  IRIX 5.2 is the current operating system release and
contains many bug fixes and enhancements utilized by IRIX Performer
1.2.   IRIS Performer 1.2 for IRIX 4.0.5 is intended only for users
who are unable to upgrade to IRIX 5.2.

------------------------------

Subject:    -6- Is there a IRIS Performer file format?
Date: 26 Oct 93 00:00:01 EST

Not at this time.  A binary file format is a desired feature for
a future release.  Currently, IRIS Performer has functionality to
load other vendors' database files at run time.

------------------------------

Subject:    -7- What database file formats can IRIS Performer read?
Date: 8 Apr 94 00:00:01 EST

IRIS Performer 1.2 includes loading utilities and file loaders for:

    - The SGI .bin, .sgo, .gfo, .poly, and .ptu formats
    - IRIS Inventor's .iv format.
    - Coryphaeus' Software .dwb format.
    - Software Systems Version 11, 13, and 14 .flt
    - The SuperViewer .sv format used in I3DM
    - Lightscape Graphics Software's .lsa and .lsb formats
    - Autodesk's AutoCAD .dxf format
    - Miscellaneous formats (.gfo, .irtp, .stla, .stlb).

For source code to loaders for MultiGen .flt versions greater than
11, contact Software Systems at [phone].

IRIS Performer 1.0 and 1.1 include database loaders for MultiGen v11
"flt", SGI "bin", and SGI "obj" formats.

------------------------------

Subject:    -8- Is there an IRIS Inventor file reader for IRIS
                Performer?
Date: 8 Apr 94 00:00:01 EST

Yes.  IRIS Performer 1.2 includes a .iv reader that will read a
subset of the IRIS Inventor 1.0 format.  A fully-functional reader
for Open Inventor files will be released via the performer mailing
list at a future time.

------------------------------

Subject:    -9- What are the .tlf files used by the Performer Town and
                Village?
Date: 8 Apr 94 00:00:01 EST

They are encrypted .flt files of the Town and Village database.
Only the "demo" version of perfly can read these files.

Unencrypted versions of the Town and Village databases are included
in the performer_friends.sw.town subsystem of Performer 1.2.

------------------------------

Subject:   -10- What are the minimum requirements for using IRIS
                Performer?
Date: 8 Apr 94 00:00:01 EST

IRIS Performer 1.2/IRIX5 requires IRIX 5.2.  This is the recommended
configuration for users of IRIS Performer.

IRIS Performer 1.2/IRIX4 requires IRIX 4.0.5.  Because IRIX 4.0.5F
added several new Graphics Library (GL) calls to support
RealityEngine features, any application that uses GL routines or
tokens found only in 4.0.5F and later, will not run properly under
4.0.5C and earlier releases.

------------------------------

Subject:   -11- Binary Compatibility on different machines
Date: 8 Apr 94 00:00:01 EST

In Performer 1.2 for IRIX 4.0.5, libpr is platform- specific with one
of two versions installed depending on whether the machines is a
RealityEngine or not.  Binaries linked on non-RealityEngine machines
will run on a RealityEngine, but not all features will be available.

Performer 1.2 for IRIX 5.2 contains a single version of libpr for all
machines.  Applications built with Performer 1.2 for Irix 5.2 are
fully compatible across machines and can run on any Irix 5.2 machine
without relinking.

------------------------------

Subject:   -12- Binary Compatibility on different releases
Date: 8 Apr 94 00:00:01 EST

IRIS Performer requires IRIX 4.0.5 or later.  Because IRIX 4.0.5F
added several new GL calls to support RealityEngine features, an
application that uses GL routines or tokens found only in 4.0.5F and
later does not run properly under 4.0.5, 4.0.5B, or 4.0.5C.  When run
on these earlier IRIX releases, an IRIS Performer application making
calls to GL functions or using GL tokens that are undefined in the
run-time environment cause run-time errors or undefined behavior.

An IRIS Performer binary compiled and linked under IRIX releases
earlier than 4.0.5F, run under IRIX 4.0.5F and later, but some
RealityEngine features are not directly accessible to the
application.  An application can still access RealityEngine features
supported automatically or explicitly through IRIS Performer when
linked with IRIS Performer shared libraries.

Running a IRIS Performer application built with IRIX 4.0.5 on IRIX
5.X is not recommended.  In particular, multiprocess applications
cannot take advantage of all processors.  Also, because IRIX 4.0.5's
relaxed shared memory accounting was replaced by a despotic and
stricter regime under IRIX 5.2, a Performer application built on
4.0.5 will need a much larger amount of swap space to be allocated up
front unless PFTMPDIR is used to specify a memory mapped file.

------------------------------

Subject:   -13- Guaranteeing Real Time performance
Date: 8 Apr 94 00:00:01 EST

Since having other applications running can effect real-time
performance, it's sometimes desirable to minimize the number of
daemons and other processes.  If you have problems achieving
real-time behavior, try the pfuLockCPU in libpfutil.  You might also
try turning off the desktop support and other daemons that are not
crucial to your application, e.g.:

   % touch ~/.disableDesktop
  or
   % mkdir ~/.desktop-<machinename>
   % touch ~/.desktop-<machinename>/nodesktop

and for total removal do:

   % chkconfig desktop off
   % chkconfig objectserver off
   % chkconfig directoryserver off
   % chkconfig fontserver off
   % chkconfig soundscheme off

Other tips:

   - Be sure to run as root.

   - Be sure to kill any clocks, gr_osview, or other tools that may
     wake up and draw themselves.

   - When multiprocessing, make sure the executable is on a local
     file system.

------------------------------

Subject:   -14- How do I make GL calls from within a IRIS Performer
                program?
Date: 26 Oct 93 00:00:01 EST

GL calls can only be made from a process that has a GL context.  In
multi-process Performer applications only the draw process has GL
context, so you must make your GL calls in a function called in the
draw process.

The pipe initialization callback, draw function callback, and node
draw callbacks are all executed in the draw process.

In an application that only will ever run single-process, GL calls
can be made from anywhere in the program.

To set up a pipe initialization callback, see the pfInitPipe() man page.
To set up a draw function callback, see the pfChanDrawFunc() man page.
To set up a node draw callback, see the pfNodeTravFuncs() man page.

------------------------------

Subject:   -15- How do I overlay graphics on top of my Performer scene?
Date: 06 Oct 93 00:00:01 EST

Typically this is done to implement a heads-up display (HUD).

In the draw function callback, the basic algorithm is:

    save state with pfPushState()
    disable textures, fog, & lighting with pfBasicState()
    save & clear projection matrix
    ortho2()
    save & clear modelling matrix
    draw()
    restore modelling matrix
    restore projection matrix
    restore state with pfPopState()

Or, you can draw your static info in the overlay planes and only
redraw it when the window receives a REDRAW event (moved, resized,
etc.).  Changing between drawing to the overlays and drawing to
regular bitplanes takes a big hit.

For things that need to be updated real-time, draw() would consist
of:

        zfunction(ZF_ALWAYS);
        zwritemask(0x0);
    draw HUD stuff
        zfunction(ZF_LEQUAL);
        zwritemask(0xffffffff);

------------------------------

Subject:   -16- What is the difference between phases FREE, FLOAT, and
                LOCK?
Date: 26 Oct 93 00:00:01 EST

PFPHASE_FREE_RUN wakes the application and draw processes up on the
next video field boundary after the draw finishes. i.e. it's
Performer's version of the usual run as-fast-as-I-can or
as-slow-as-I-must mode that most simple graphics programs use.

PFPHASE_FLOAT wakes the application up only on frame boundaries, i.e.
time = n*(1/frame_rate).  However, the draw process "floats" with
respect to the frame rate and wakes up on the next possible field
boundary and then does a swapbuffers() when it's done, regardless of
whether it finished drawing in time for the desired frame rate.
Hence you see every frame that's drawn to the backbuffer, but it may
not appear at exactly the time for which it was planned.  If you
never frame extend, it behaves like PFPHASE_FIXED.  Latency is
variable.

PFPHASE_LOCK wakes the application and draw up only on frame
boundaries and only swaps on frame boundaries.  The advantage is that
each new image always appears at precisely the time for which it was
rendered.  The disadvantage is that if the draw runs even slightly
over a frame time, you skip that entire frame and are stuck with an
outdated picture for a frame.  Latency is fixed.

For more information see the pfPhase() man page or section 7.1.2 of
the PFPG.

------------------------------

Subject:   -17- Which rendering primitives does IRIS Performer support?
Date: 8 Apr 94 00:00:01 EST

Points (PFGS_POINTS),
Independent line segments (PFGS_LINES),
Connected line strips (PFGS_LINESTRIPS),
Flat connected line strips (PFGS_FLAT_LINESTRIPS),
Independent Triangles (PFGS_TRIS),
Connected triangle strips (PFGS_TRISTRIPS),
Flat Connected triangle strips (PFGS_FLAT_TRISTRIPS),
Independent quadrilaterals (PFGS_QUADS).

See the pfGeoSet(3pf) man page for more information.

------------------------------

Subject:   -18- How do I do triangle meshes in Performer?
Date: 06 Oct 93 00:00:01 EST

You must change your triangle meshes to triangle strips by hand.
In Performer 1.2, pfuMeshGSet (from libpfutil) will do this for you.

------------------------------

Subject:   -19- What is pfInit(): mmap failed for /dev/zero ?
Date: 26 Oct 93 00:00:01 EST

This means that you tried to run a Performer 1.0 application
(such as a 4.x version of perfly) on a machine running IRIX 5.x.
Virtual memory management is different in IRIX 5.x.  In order
for your program to work properly you must:

   % setenv PFTMPDIR /usr/tmp

------------------------------

Subject:   -20- =============== KNOWN PROBLEMS ===============
Date: 8 Apr 94 00:00:01 EST

------------------------------

Subject:   -21- Performer Town or Village demos
Date: 26 Oct 93 00:00:01 EST

It was reported that perfly would cause an Onyx RE or VTX running
IRIX 5.0 to hang.  This was fixed in 5.0.1.

In 5.0.1, perfly would generate floating point exceptions due to a
bug in the font manager library (libfm).  This was fixed in 5.1.

In 5.x, the town and village demos could sometimes be 'jerky'.  This
is better in 5.2.  See the above section on "Guaranteeing Real Time
performance"

------------------------------

Subject:   -22- Antialiasing
Date: 8 Apr 94 00:00:01 EST

When it is not multisampling, pfAntialias can significantly degrade
performance.  Specifically, on non-RealityEngine systems, use
pfAntialias only for lines and points.

------------------------------

Subject:   -23- Z buffer configuration on 4.0.5 RealityEngine
Date: 8 Apr 94 00:00:01 EST

Z buffer config on 4.0.5 RealityEngine: On some versions of IRIX
4.0.5, mssize(4,24,1) (the default by pfAntiAlias) generates an
unusable Z configuration.  For these machines, call mssize(4,32,1)
followed by gconfig() in your pipe initialization routine and do not
attempt to toggle antialiasing.

------------------------------

Subject:   -24- Coplanar Polygons & pfDecal on certain platforms
Date: 8 Apr 94 00:00:01 EST

pfDecal works only on machines that support the stencil or
displacepolygon command.  The default decaling mode for PFDECAL_BASE
now uses displacepolygon instead of stencil.  This can significantly
improve rendering performance but can result in visual anomalies
where layer polygons incorrectly "poke" through other geometry.  If
you wish the old behavior then specify the PFDECAL_BASE_HIGH_QUALITY
token.

------------------------------

Subject:   -25- Networked graphics
Date: 8 Apr 94 00:00:01 EST

Networked graphics: libpf does not support applications that use
networked GL, that is DGL.  However, applications using libpr can use
DGL.

------------------------------

Subject:   -26- Transparency
Date: 8 Apr 94 00:00:01 EST

pfTransparency works only on machines that support either
blendfunction or multisampling.

Sometimes users report that their transparency seems quantized.  This
is not a bug -- Performer defaults to using Multisample transparency
(msalpha) when multisampling is enabled, instead of using the
"standard" (blendfunction) transparency mechanism.

Multisample transparency is faster but has much less resolution, and
so less quality.  Standard transparency using blendfunction is
slower, but the quality is very good.

To force Performer to use higher-quality (but slower) transparency
when multisampling,

1.0/1.1:  pfGStateMode (gstate, PFSTATE_TRANSPARENCY, 2);
1.2:      pfGStateMode (gstate, PFSTATE_TRANSPARENCY, PFTR_HIGH_QUALITY);
                          aka PFTR_BLEND_ALPHA

In 1.0/1.1 the BLEND_ALPHA token was not exposed, but just use '2'.
Be sure to revisit this code when you port to 1.2, as the token has
changed.

See the pfTransparency(3pf) man page for more details.

------------------------------

Subject:   -27- Frame control on low- and mid-range machines
Date: 8 Apr 94 00:00:01 EST

Currently, the video clock (pfInitVClock, pfGetVClock, pfVClockSync)
is supported only on systems with VGX, VGXT, RealityEngine,
RealityEngine2, Elan, XS, and Extreme graphics hardware.  On other
systems, pfVClockSync returns immediately.  Because libpf normally
uses pfVClockSync for frame rate control, frame control is not
rigorous on other platforms.

------------------------------

Subject:   -28- Timing on pre-1992 platforms
Date: 8 Apr 94 00:00:01 EST

Several libpf functions require high-resolution timing information.
On most recent machines (Indy, Indigo, Indigo2, 4D/35 and Onyx) and
PowerSeries or Crimson machines with IO3 boards, IRIS Performer uses
special hardware counters with sub-microsecond resolution.  (The IO3
board is standard on Crimson and recent 4D/300 and 4D/400 machines.
You can check for it with the hinv(1M) command.)

On other platforms, for example, those with IO2 boards, the
time-of-day clock is used, which, by default, has a 10 ms
resolution.  This resolution is inadequate for many libpf functions,
including animation sequences (pfSequence), graphics load computation
(pfChanStress), and the display of accurate channel statistics
(pfDrawChanStats).

To use any of these features on machines without high- resolution
hardware timers, enable fast timers.  See the man page for ftimer for
more information.  Frame rate control particularly bad on machines
which lack both a fast clock and the video clock used by
pfVClockSync.


------------------------------

Subject:   -29- 1.2 Bug Billboard normals and intersections
Date: 8 Apr 94 00:00:01 EST

During rendering, pfBillboard normals are not affected by the
transformation applied to make the geometry follow the eye.
Intersection testing of line segments (pfSegsIsectNode) against the
pfGeoSet's geometry and bounding box are not yet implemented; only
the bounding sphere of the entire pfBillboard is available.

------------------------------

Subject:   -30- 1.2 Bug Billboards with multiple pfGeoSets
Date: 8 Apr 94 00:00:01 EST

Using pfBillboards with more than one pfGeoSet sometimes causes a
segmentation violation during the first cull traversal.  Workaround:
use only a single pfGeoSet per pfBillboard at some cost in
performance.

------------------------------

Subject:   -31- 1.2 Bug Flattening transformation hierarchies
Date: 8 Apr 94 00:00:01 EST

pfFlatten does not work properly on pfGeodes that share pfGeoSets
with other pfGeodes.

------------------------------

Subject:   -32- 1.2 Bug Gangdraw and cursor loading
Date: 8 Apr 94 00:00:01 EST

Loading the cursor with ganged swapbuffers (external swapready wire)
hangs graphics.  Workaround:  don't load the cursor or run
applications which change it.

------------------------------

Subject:   -33- 1.2 libpf Bug Hang on Exit, 5.2 VGX
Date: 8 Apr 94 00:00:01 EST

On VGXT running 5.2, calling pfExit when the phase is PFPHASE_LOCK or
PFPHASE_FLOAT can leave an inactive window and DRAW process.
Workaround: switch to PFPHASE_FLOAT or PFPHASE_FREE before exiting or
kill -9 <pid> afterwards.

------------------------------

Subject:   -34- 1.2 libpf Cull with overlapped draw latency
Date: 8 Apr 94 00:00:01 EST

When running PFPHASE_LIMIT or PFPHASE_FREE, the draw can start late
resulting in higher latency.

------------------------------

Subject:   -35- 1.2 libpf Cull with overlapped draw hang
Date: 8 Apr 94 00:00:01 EST

When running PFPHASE_LIMIT or PFPHASE_FREE, with processes locked and
non-degrading priorities, it is possible to lock out the X server and
hang the system.

------------------------------

Subject:   -36- 1.2 libpf Transparency Sorting
Date: 8 Apr 94 00:00:01 EST

When the PFCULL_SORT mode of pfChanTravMode is set, transparent
objects are drawn after all opaque geometry.  However, transparent
objects are not sorted back to front among themselves, so visual
anomalies can result when using blended transparency.  Workaround:
use multisample transparency (PFTR_MS_ALPHA), if available.

------------------------------

Subject:   -37- 1.2 libpf Multiple EarthSky fog
Date: 8 Apr 94 00:00:01 EST

When using multiple pipes which share pfEarthSky fog set by
pfESkyFog, the fog may appear to change densities and flash.
Workaround: to guarantee that pfClearChan is not called
simultaneously by more than one pipe.  This may be accomplished with
a hardware spin lock (see usnewlock)

------------------------------

Subject:   -38- 1.2 libpf Bug Limit Phase
Date: 8 Apr 94 00:00:01 EST

The PFPHASE_LIMIT mode of pfPhase only works when the draw stage is
configured as a separate process.  For example, the PFMP_APP_CULLDRAW
mode to pfMultiprocess specifies that the cull and draw stages are
combined into a single process and so will not be affected by a LIMIT
phase.

------------------------------

Subject:   -39- 1.2 libpr Highlighting when using wireframe
Date: 8 Apr 94 00:00:01 EST

Using highlighting when in wireframe mode can cause random,
flickering, or otherwise misbehaved polygons.

------------------------------

Subject:   -40- 1.2 libpf APPCULLDRAW does not honor LIMIT/FLOAT/LOCK
                phases
Date: 8 Apr 94 00:00:01 EST

When in PFMP_APPCULLDRAW mode, both FREE_RUN and LIMIT act the same;
as do FLOAT and LOCK.

------------------------------

Subject:   -41- 1.2 libpf Phase toggling overlapped cull and draw
Date: 8 Apr 94 00:00:01 EST

When running in the PFMP_CULLoDRAW multiprocessing mode, changing the
phase from PFPHASE_LOCK or PFPHASE_FLOAT to PFPHASE_FREE_RUN or
PFPHASE_LIMIT can cause the application to deadlock.

In perfly, rapidly toggling the phase when running with the
PFMP_CULLoDRAW multiprocessing model ("perfly -m 65540" or "perfly -m
65542") can cause the application to hang.

Workaround: toggle only once every few frames or not at all.

------------------------------

Subject:   -42- 1.2 libpf pfDataPool warning on exit
Date: 8 Apr 94 00:00:01 EST

A warning similar to the following sometimes occurs when a sample
program exits: "Performer Warning (2):  pfReleaseDPool() Could not
unlink arena shared memory /usr/tmp/pfUtilDataPool11638.pfdpool."
This warning is harmless and can be ignored.

------------------------------

Subject:   -43- 1.2 libpf Multi-channel stats warning messages
Date: 8 Apr 94 00:00:01 EST

When a multi-channel libpf application enables libpr pfStats modes
(such as graphics statistics -- PFSTATS_GFX) in multiple channels at
the same time, warning messages are printed every frame.  The
calculated statistics will be correct.  To stop the stream of warning
messages, raise the pfNotifyLevel in the program or set the
enviornment variable PFNFYLEVEL to a value smaller than 2.

------------------------------

Subject:   -44- 1.2 libpf Video warnings on Indy when multiprocessed
Date: 8 Apr 94 00:00:01 EST

When an application on an Indy is forced to run the APP and DRAW in
separate processes, e.g.  pfMultiprocess(PFMP_APP_CULLDRAW),
pfGetVideoRate warnings are printed when process timing stats are
on.  To stop the stream of warning messages, raise the pfNotifyLevel
in the program or set the enviornment variable PFNFYLEVEL to a value
smaller than 2.

------------------------------

Subject:   -45- 1.2 stats Frame statistics for lightpoints
Date: 8 Apr 94 00:00:01 EST

pfFrameStats for visible uni-directional and bi-directional
pfLightPoint nodes and points are incorrect.  These statistics are
part of the pfFrameStats database statistics (PFFSTATS_DB) and these
specific counts are incorrect.  However, the counts for total number
of visible pfLightPoint nodes and points are correct, and so are the
counts for Omni-directional pfLightPoint nodes and points.  However,
these numbers are only counted when PFFSTATS_CULL are enabled.

------------------------------

Subject:   -46- 1.2 stats Pixel fill statistics under 4.0.5 on
                RealityEngine
Date: 8 Apr 94 00:00:01 EST

Under 4.0.5, fill statistics do not work when multisampling.
Workaround: turn off multisampling.

------------------------------

Subject:   -47- 1.2 libpr Directional pfLightPoints
Date: 8 Apr 94 00:00:01 EST

Specifying a pfLightPoint node as PFLP_UNIDIRECTIONAL or
PFLP_BIDIRECTIONAL can cause a core dump in pfLightPoint::cull.
Workaround: set the color of the first light point with
pfLPointColor(lp, 0, color) before calling pfLPointShape.

------------------------------

Subject:   -48- 1.2 libpfutil pfuCollide is jerky
Date: 8 Apr 94 00:00:01 EST

The collision model jerks and bounces when you keep hitting something.

------------------------------

Subject:   -49- 1.2 libpfutil pfuSaveImage broken
Date: 8 Apr 94 00:00:01 EST

The image file generated by pfuSaveImage is bogus.

------------------------------

Subject:   -50- 1.2 libpfsgi pfLoadDxf loader is incomplete
Date: 8 Apr 94 00:00:01 EST

The DXF loader does not fully support the format.

------------------------------

Subject:   -51- 1.2 libpfsgi pfLoadIv loader is incomplete
Date: 8 Apr 94 00:00:01 EST

The IRIS Inventor loader reads a subset of the IRIS Inventor 1.0
format.

------------------------------

Subject:   -52- 1.2 GLX Overlay text with GLX on 4.0.5
Date: 8 Apr 94 00:00:01 EST

In the sample programs (e.g. perfly) on some platforms, sometimes
drawing messages (pfuDrawMessageCI) to the overlay planes in GLX mode
doesn't work under 4.0.5.  Workaround: use only in GL mode (e.g. do
not use "perfly -x") or upgrade to IRIX 5.2.

------------------------------

Subject:   -53- 1.2 GLX Toggling antialiasing with GLX on 4.0.5
                RealityEngine
Date: 8 Apr 94 00:00:01 EST

Toggling antialiasing in the sample programs running in GLX mode on a
4.0.5 RealityEngine apparently confuses the graphics pipe and causes
wild texturing.  Workaround: use only in GL mode (e.g. do not use
"perfly -x") or upgrade to IRIX 5.2.

------------------------------

Subject:   -54- 1.2 GLX Toggling antialiasing with GLX on any
                RealityEngine
Date: 8 Apr 94 00:00:01 EST

When antialiasing is toggled with the GUI in GLX mode, the GL window
changes.  As each texture textures first comes into view, it is
downloaded to the graphics hardware.  Occasional pauses will be seen
until all textures are reloaded in the graphics hardware.  This can
be avoided by redownloading all textures (pfuDownloadTexList).

------------------------------

Subject:   -55- 1.2 GLX on 4.0.5 Indigo, sample programs hang on
                startup.
Date: 8 Apr 94 00:00:01 EST

Some sample programs will hang on startup if in GLX mode.
Workaround:  start up only in GL mode (e.g. do not use "perfly -x")
or upgrade to IRIX 5.2.

------------------------------

Subject:   -56- 1.2 samples smallfly drive models broken
Date: 8 Apr 94 00:00:01 EST

Toggling the drive-model button in smallfly can cause unexpected
results.

------------------------------

Subject:   -57- 1.2 samples pickfly drops core under abuse
Date: 8 Apr 94 00:00:01 EST

When aggressively navigating the hierarchy, the number of pfSCSes in
the scene graph can exceed the maximum libpf traversal depth of 64.

------------------------------

Subject:   -58- 1.2 samples detail example broken on 4.0.5
Date: 8 Apr 94 00:00:01 EST

The example program sample/pguide/libpf/progs/detail.c doesn't run
properly under 4.0.5.  Workaround: upgrade to 5.2.

------------------------------

Subject:   -59- 1.2 friends Belvis makefile requires pmake
Date: 8 Apr 94 00:00:01 EST

The makefile for the belvis demo in the Computer Arts and Development
section requires the pmake utility.  Workaround: install
dev.sw.make.

------------------------------

Subject:   -60- 1.2 friends Toon has bad models and textures
Date: 8 Apr 94 00:00:01 EST

Some of the textures are mixed up in toon town.

------------------------------

Subject:   -61- 1.2 docs pfuGetGLXWin wrong on reference page
Date: 8 Apr 94 00:00:01 EST

The prototype in the man page should read: "extern void
pfuGetGLXWin(pfPipe *_pipe, pfuGLXWindow *_glxWin);" pfuGetGLXWin
copies the active GLX windows (normal and overlay) for the specified
pipe into the provided pfuGLXWindow structure.  The active windows
change when a different GLX visual is requested.

------------------------------

Subject:   -62- 1.2 docs pfuLockDownApp gives the incorrect location
Date: 8 Apr 94 00:00:01 EST

pfuLockDownApp gives the incorrect location for the procsetup.c
example: The correct location for this example is:

   /usr/src/Performer/src/pguide/libpfutil/progs/procsetup.c

Additionally, the reference page should mention the example

   /usr/src/Performer/src/pguide/libpf/progs/bench.c

------------------------------

Subject:   -63- 1.1 Bug with FP underflow
Date: 26 Oct 93 00:00:01 EST

The cull process could encounter an FP underflow that could
periodically affect cull performance.

------------------------------

Subject:   -64- 1.1 Bug with Multipipe Onyx
Date: 26 Oct 93 00:00:01 EST

There is a bug in the 1.1 multipipe code.  The symptom is a
core dump and an error like:

   Performer Fatal (4):pfFree() pointer 0x9c9350 not from pfMalloc

The workaround is to do the following after you've created
a channel with pfNewChan:

   ((long**)chan)[3] = NULL;

This workaround MUST NOT BE USED in Performer 1.2 applications.

------------------------------

Subject:   -65- 1.1 Bug Installing on Indy or Indigo2 XL
Date: 8 Apr 94 00:00:01 EST

The problems are related to the way that Performer recognizes the
graphics hardware in the machine.  Since the Indy was introduced
after Performer 1.1 released, Performer is unable to match the
graphics type (NEWPORT) with the hardware types it knows.  This
effects both the installation and run-time applications.

/usr/lib/libpr.a, /usr/lib/libpr-g.a, /usr/src/Performer/demo/perfly,
and /usr/src/Performer/src/perfly/Makefile are machine-tagged in inst
as platform-specific and will not be installed by default.

WORKAROUND:  You must remove IRIS Performer 1.1 from your machine and
re-install, explicitly defining the graphics hardware type.  LIGHT
(Entry) graphics is the closest approximation to NEWPORT.

        % su
        # versions remove performer_eoe
        # versions remove performer_dev
        # inst -f <pathname> -m GFXBOARD=LIGHT

------------------------------

Subject:   -66- 1.1 Bug Unable to determine Indy graphics type
Date: 8 Apr 94 00:00:01 EST

Performer 1.1 applications on Indy display the message: "unable to
determine graphics type -1.  Default: VENICE"

WORKAROUND:  The above message means that Performer was unable to
match NEWPORT graphics to a known graphics type, and has defaulted to
VENICE (RealityEngine).  This could cause some anomalous behavior in
your application.  There is no specific workaround at this time.

------------------------------

Subject:   -67- 1.1 Bug perfly cannot find libpf.so on Indy running 5.1
Date: 8 Apr 94 00:00:01 EST

/usr/src/Performer/demo/perfly fails with the error message:
"perfly: rld: Fatal Error: cannot find soname 'libpf.so'"

WORKAROUND:  You must recompile perfly from the source code provided
in /usr/src/Performer/src/perfly.

------------------------------

Subject:   -68- 1.1 Bug perfly FP error messages in 5.0.1
Date: 8 Apr 94 00:00:01 EST

perfly prints the following error message(s) several times each
frame:

    "Performer Info:FP division by zero"
    "Performer Info:FP infinity minus infinity"

WORKAROUND:  This is caused by a bug in IRIS GL and is not a fatal
error.  Run perfly with the "-n 2" option to disable these (and any
other) informational messages.

------------------------------

Subject:   -69- 1.1 Bug Installation on IRIX 5.2 - missing prerequisites
Date: 8 Apr 94 00:00:01 EST

When trying to install IRIS Performer 1.1 on a machine running IRIX
5.2, you will get an error regarding a missing prerequisite,
"dev.sw.libC".  This subsystem contained the C++ runtime library.  In
5.2 it has been renamed to "c++_eoe.sw.lib".

WORKAROUND:  'set rulesoverride on' from within inst.

------------------------------

Subject:   -70- 1.0/1.1 Bug intersections with pfSwitch'es
Date: 26 Oct 93 00:00:01 EST

Intersections with pfSwitch'es whose value is PFSWITCH_OFF could
cause a core dump.

------------------------------

Subject:   -71- 1.0/1.1 Bug with pfTexture()
Date: 26 Oct 93 00:00:01 EST

On RealityEngine systems, EXTERNAL format was ignored.

------------------------------

Subject:   -72- 1.0/1.1 Bug with pfAntiAlias()
Date: 26 Oct 93 00:00:01 EST

On RealityEngine systems, pfAntialias(PFAA_OFF) did not turn off
multisampling.

------------------------------

Subject:   -73- 1.0/1.1 Bug with pfFlatten()
Date: 26 Oct 93 00:00:01 EST

pfFlatten did not dirty bounding spheres of flattened nodes so they
had improper bounds and would not cull correctly.

------------------------------

Subject:   -74- 1.0/1.1 Bug with pfSequences
Date: 26 Oct 93 00:00:01 EST

pfSequences: PFSEQ_RESUME ignored children's display times and drew
subsequent children for 1 frame only.

------------------------------

Subject:   -75- 1.0/1.1 Bug with pfClosestPtOnPlane()
Date: 26 Oct 93 00:00:01 EST

pfClosestPtOnPlane returned wrong result.  Also, the man page had the
wrong prototype.

------------------------------

Subject:   -76- 1.0/1.1 Bug on ELAN/XS with wireframe PFGS_QUADS
Date: 26 Oct 93 00:00:01 EST

On EXPRESS Graphics platforms (XS, XS24, ELAN, etc), wireframe quads
have a stray line from one vertex to "infinity" when displayed in
wireframe mode.

------------------------------

Subject:   -77- 1.0 Doc Bug in pfMakePolarSeg() man page
Date: 26 Oct 93 00:00:01 EST

The man page for pfMakePolarSeg contradicts itself with respect to
the meaning of azimuth and elevation. The correct paragraph should
be:

    pfMakePolarSeg sets dst to the segment which starts at pos
    and has length length and points in the direction specified
    by azi and elev.  azi specifies the azimuth (or heading),
    which is the angle which the projection of the segment in the
    X-Y plane makes with the +Y axis.  elev specifies the
    elevation (or pitch), the angle with respect to the X-Y
    plane.  The positive Y axis is azi=0 and elev=0.  Azimuth
    follows the right hand rule about the +Z azis, e.g. -  +90
    degrees is the -X axis.  Similarly, elevation follows the
    right hand rule about the X axis, e.g. -  +90 degrees is the
    +Z axis.

Note that in IRIS Performer 1.0, an azi and elev of 0.0 is equivalent
to the +X axis while in 1.1, this has been changed to the +Y axis.

------------------------------

Subject:   -78- 1.0 Doc Bug in pfDispList() man page
Date: 26 Oct 93 00:00:01 EST

The pfDispList man page says the size argument is in bytes; it should
say words.

------------------------------

Subject:   -79- 1.0 Doc Bug in PFPG (simple.c)
Date: 26 Oct 93 00:00:01 EST

The program simple.c in the IRIS Performer Programming Guide (PFPG)
does not bind a light and draws a black image on Elan systems.  The
corrected version, which creates and binds a light in the pipe
initialization callback, is in /usr/src/Performer/src/pguide

------------------------------

Subject:   -80- 1.0 Bug in pfGetTime()
Date: 26 Oct 93 00:00:01 EST

In 1.0, pfGetTime() would occasionally return bad values (off by
4000+ seconds) on Indigo2 and machines without a fast counter, e.g.
PowerSeries/IO2.

There was no workaround.

------------------------------

Subject:   -81- 1.0 Bug in pfNodeBBox()
Date: 26 Oct 93 00:00:01 EST

pfNodeBBox did not set the bounding box of a node.  A symptom was
that the bounding boxes of the node would not change when modifying a
parent pfDCS.

The workaround was to OR the value 0x0010 into the mode, e.g.-

   pfNodeBBox(node, &bbox, PFN_BMODE_STATIC | 0x0010);

------------------------------

Subject:   -82- 1.0 Bug in pfInitGfx() with Z-buffer on RealityEngine
Date: 26 Oct 93 00:00:01 EST

pfInitGfx on RealityEngines would call lsetdepth(0x0, 0x0),
essentially disabling zbuffering.

The workaround was to call lsetdepth explicitly after pfInitGfx,
in the pipe initialization callback.

------------------------------

Subject:   -83- 1.0 Bug in libpfflt combineLODs()
Date: 26 Oct 93 00:00:01 EST

combineLODs() in the MultiGen .flt converter (in file hier.c) did not
set the LOD center of combined LODs.  This would result in strange
LOD behavior for LODs which were not modelled about the origin.

------------------------------

Subject:   -84- 1.0 Bug with two-sided material and pfMtlColorMode()
Date: 26 Oct 93 00:00:01 EST

Applying a back-sided material which had a color mode
(pfMtlColorMode), would set the GL lmcolor mode. Since
IrisGL does not support lmcolor for back-sided materials,
this could have caused front-sided materials to use an
improper lmcolor mode.

------------------------------

Subject:   -85- 1.0 Bug in pfFilePath()
Date: 26 Oct 93 00:00:01 EST

pfFilePath would exit with a FATAL error if it was called twice.

------------------------------

Subject:   -86- 1.0 Bug in pfGetCurGState()
Date: 26 Oct 93 00:00:01 EST

pfGetCurGState returned a pfGeoState which was the top of the state
stack rather than the most recently applied pfGeoState.

------------------------------

Subject:   -87- 1.0 Bug in pfGetCurState()
Date: 26 Oct 93 00:00:01 EST

pfGetCurState returned a pfGeoState which was the top of the state
stack rather than the current pfState.

------------------------------

Subject:   -88- 1.0 Bug with cloned scenes
Date: 26 Oct 93 00:00:01 EST

pfClone()'ed scenes were not properly cleaned and did not properly
propagate updates.  In particular, cloned pfSequences did not work.

------------------------------

Subject:   -89- 1.0 Bug intersections in collide.c
Date: 26 Oct 93 00:00:01 EST

collide.c was shipped with a hardwired intersection mode which turned
off intersection caching, substantially reducing intersection
performance.

------------------------------

Subject:   -90- 1.0 Bug with flattened pfLightPoints
Date: 26 Oct 93 00:00:01 EST

pfFlatten()'ed pfLightPoints were broken for multiprocessing modes
when the application and cull processes were separate.

------------------------------

Subject:   -91- 1.0 Bug intersections with pfSequences
Date: 26 Oct 93 00:00:01 EST

Intersections with pfSequences could sometimes turn them off
(PFSEQ_STOP).

------------------------------

Subject:   -92- 1.0 Bug intersections with non-indexed quads
Date: 26 Oct 93 00:00:01 EST

Intersection caching for non-indexed quads was broken and could case
a core dump when intersection with pfGeoSets of this type.

------------------------------

End of sgi/faq/performer Digest
******************************
--
The SGI FAQ group                                [e-mail]
Finger us for info on the SGI FAQs, or look in viz.tamu.edu:/pub/sgi.